<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "DTD/xhtml1-strict.dtd">
<html>
  <head>
    <title>API docs for &ldquo;pymine.api.minekey.MineKey&rdquo;</title>
    <meta content="text/html;charset=utf-8" http-equiv="Content-Type" />
    <link href="apidocs.css" type="text/css" rel="stylesheet" />
    
    
  </head>
  <body>
    <h1 class="class">Class p.a.m.MineKey:</h1>
    <p>
      <span id="part">Part of <a href="pymine.html">pymine</a>.<a href="pymine.api.html">api</a>.<a href="pymine.api.minekey.html">minekey</a></span>
      
      <a href="classIndex.html#pymine.api.minekey.MineKey">View In Hierarchy</a>
    </p>
    <div>
      
    </div>
    <div class="undocumented">No class docstring</div>
    
    
    <div id="splitTables">
      <table class="children sortable" id="id8">
  
  
  
  
  <tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#__init__">__init__</a></td>
    <td><span>Create a nu-format minekey.</span></td>
  </tr><tr class="classmethod">
    
    
    <td>Class Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#create_feedmk">create_feedmk</a></td>
    <td><span>assuming 'feed' is a valid Feed object instance, return a</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#__str__">__str__</a></td>
    <td><span>returns the minekey information WITHOUT hmac, in the following 
format:</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#mkerr">mkerr</a></td>
    <td><span>create a diag string to drop into an exception</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#validate">validate</a></td>
    <td><span>does a variety of sanity checks on self and throws a</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#get_hmac">get_hmac</a></td>
    <td><span>computes and returns the hmac for this minekey</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#get_feed">get_feed</a></td>
    <td><span>return a (cached) copy of the feed object corresponding to this 
minekey</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#get_item">get_item</a></td>
    <td><span class="undocumented">Undocumented</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#get_ext">get_ext</a></td>
    <td><span>return a viable extention for this key</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#key">key</a></td>
    <td><span>validates, and then returns the minekey information WITH hmac, in the 
following format:</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#permalink">permalink</a></td>
    <td><span>takes the result of self.key() and embeds / returns it in a</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#http_path">http_path</a></td>
    <td><span>returns the http://host.domain:port/ for this mine, for template use</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#clone">clone</a></td>
    <td><span>clone this minekey for further futzing</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#spawn_data">spawn_data</a></td>
    <td><span>from this minekey, spawn a new minekey object for the same</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#spawn_icon">spawn_icon</a></td>
    <td><span>from this minekey, spawn a new minekey object for the same</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#spawn_icon_self">spawn_icon_self</a></td>
    <td><span>return spawn_icon for self</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#spawn_submit">spawn_submit</a></td>
    <td><span>from this minekey, spawn a new minekey object for comment</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#spawn_submit_self">spawn_submit_self</a></td>
    <td><span>from this minekey, spawn a new minekey object for comment</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#access_check">access_check</a></td>
    <td><span>checks the per-feed security policy and enforces it</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#response">response</a></td>
    <td><span>returns the appropriate http response for this minekey</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.api.minekey.MineKey.html#rewrite_html">rewrite_html</a></td>
    <td><span>using the context of this minekey, rewrite the blob of HTML</span></td>
  </tr>
  
</table>
      
      
    </div>
    
    
    
    <div class="function">
        <a name="pymine.api.minekey.MineKey.__init__"></a>
        <a name="__init__"></a>
        <div class="functionHeader">
        
        def __init__(self, request, **kwargs):
        
      </div>
        <div class="functionBody">
          
          <div>Create a nu-format minekey.</p>
<p>request: request object for URL-generation purposes</p>
<p>kwargs include: type: one of ('data', 'icon', 'submit') fid: integer 
feed id &gt; 0 fversion: integer feed version number &gt; 0 iid: integer 
item id &gt;= 0 depth: integer depth &gt; 0 ext: regexp ^\w+$ hmac: hmac 
against which to check this minekey</p>
<p>if either 'hmac' is supplied, or if kwargs[enforce_hmac_check] evaluates
to True, a hmac test is performed; this option is provided to allow the 
programmer to ENFORCE a hmac check, just in case something higher-up 
permits code to slide through that sets hmac=None/False/0<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.create_feedmk"></a>
        <a name="create_feedmk"></a>
        <div class="functionHeader">
        @classmethod<br />
        def create_feedmk(klass, request, feed):
        
      </div>
        <div class="functionBody">
          
          <div>assuming 'feed' is a valid Feed object instance, return a minekey which 
eventually will yield the FEEDXML feed for this Feed</p>
<p>There once was a time when Feed objects were called 'Relations' because 
they held data pertinent to the relationship between a mine user and one of
his subscribers; this concept seemed to the programmer to be distinct from 
(say) the feeds that would be generated.</p>
<p>However this terminology was deemed &quot;confusing&quot; by the Mine 
design team and so now we have Feed objects (one thing) which generate 
feeds (another thing entirely) - obvious, n'est-ce pas?<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.__str__"></a>
        <a name="__str__"></a>
        <div class="functionHeader">
        
        def __str__(self):
        
      </div>
        <div class="functionBody">
          
          <div>returns the minekey information WITHOUT hmac, in the following 
format:</p>
<p>fid/fversion/iid/depth/type<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.mkerr"></a>
        <a name="mkerr"></a>
        <div class="functionHeader">
        
        def mkerr(self, *args):
        
      </div>
        <div class="functionBody">
          
          <div>create a diag string to drop into an exception<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.validate"></a>
        <a name="validate"></a>
        <div class="functionHeader">
        
        def validate(self):
        
      </div>
        <div class="functionBody">
          
          <div>does a variety of sanity checks on self and throws a RuntimeError if 
surprised; this does not enforce security checks (see access_check()) but 
instead checks the plausible validity of the key itself.</p>
<p>for a minekey such as &quot;HMAC/42/1/11/2/data.dat&quot; - the 
validation covers everything from &quot;HMAC&quot; to &quot;data&quot; 
inclusive; the trailing &quot;.dat&quot; is considered advisory.<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.get_hmac"></a>
        <a name="get_hmac"></a>
        <div class="functionHeader">
        
        def get_hmac(self, enforce_hmac_check=False):
        
      </div>
        <div class="functionBody">
          
          <div>computes and returns the hmac for this minekey</p>
<p>if enforce_hmac_check evaluates as True (default False) then the 
computed hmac is compared against the hmac declared at instantiation; if 
there is a difference, an exception is thrown.<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.get_feed"></a>
        <a name="get_feed"></a>
        <div class="functionHeader">
        
        def get_feed(self):
        
      </div>
        <div class="functionBody">
          
          <div>return a (cached) copy of the feed object corresponding to this 
minekey<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.get_item"></a>
        <a name="get_item"></a>
        <div class="functionHeader">
        
        def get_item(self):
        
      </div>
        <div class="functionBody">
          
          <div class="undocumented">Undocumented</div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.get_ext"></a>
        <a name="get_ext"></a>
        <div class="functionHeader">
        
        def get_ext(self):
        
      </div>
        <div class="functionBody">
          
          <div>return a viable extention for this key<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.key"></a>
        <a name="key"></a>
        <div class="functionHeader">
        
        def key(self):
        
      </div>
        <div class="functionBody">
          
          <div>validates, and then returns the minekey information WITH hmac, in the 
following format:</p>
<p>hmac/[fid/fversion/iid/depth/type].ext</p>
<p>...the [central portion] being generated by __str__() and protected by 
hmac<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.permalink"></a>
        <a name="permalink"></a>
        <div class="functionHeader">
        
        def permalink(self):
        
      </div>
        <div class="functionBody">
          
          <div>takes the result of self.key() and embeds / returns it in a permalink 
string for this mine; for full pathname resolution it needs 'request' to be
set in the minekey constructor, or in a parent thereof<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.http_path"></a>
        <a name="http_path"></a>
        <div class="functionHeader">
        
        def http_path(self):
        
      </div>
        <div class="functionBody">
          
          <div>returns the http://host.domain:port/ for this mine, for template use<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.clone"></a>
        <a name="clone"></a>
        <div class="functionHeader">
        
        def clone(self):
        
      </div>
        <div class="functionBody">
          
          <div>clone this minekey for further futzing</p>
<p>if you do futz manually, remember to do minekey.validate()<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.spawn_data"></a>
        <a name="spawn_data"></a>
        <div class="functionHeader">
        
        def spawn_data(self, iid):
        
      </div>
        <div class="functionBody">
          
          <div>from this minekey, spawn a new minekey object for the same fid/fversion,
but for a different iid, decrementing depth<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.spawn_icon"></a>
        <a name="spawn_icon"></a>
        <div class="functionHeader">
        
        def spawn_icon(self, iid):
        
      </div>
        <div class="functionBody">
          
          <div>from this minekey, spawn a new minekey object for the same fid/fversion,
but for a different iid's icon, decrementing depth<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.spawn_icon_self"></a>
        <a name="spawn_icon_self"></a>
        <div class="functionHeader">
        
        def spawn_icon_self(self):
        
      </div>
        <div class="functionBody">
          
          <div>return spawn_icon for self<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.spawn_submit"></a>
        <a name="spawn_submit"></a>
        <div class="functionHeader">
        
        def spawn_submit(self, iid):
        
      </div>
        <div class="functionBody">
          
          <div>from this minekey, spawn a new minekey object for comment submission, 
setting depth=1 if depth is currently legal<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.spawn_submit_self"></a>
        <a name="spawn_submit_self"></a>
        <div class="functionHeader">
        
        def spawn_submit_self(self):
        
      </div>
        <div class="functionBody">
          
          <div>from this minekey, spawn a new minekey object for comment submission, 
setting depth=1 if depth is currently legal<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.access_check"></a>
        <a name="access_check"></a>
        <div class="functionHeader">
        
        def access_check(self):
        
      </div>
        <div class="functionBody">
          
          <div>checks the per-feed security policy and enforces it<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.response"></a>
        <a name="response"></a>
        <div class="functionHeader">
        
        def response(self):
        
      </div>
        <div class="functionBody">
          
          <div>returns the appropriate http response for this minekey<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.api.minekey.MineKey.rewrite_html"></a>
        <a name="rewrite_html"></a>
        <div class="functionHeader">
        
        def rewrite_html(self, html):
        
      </div>
        <div class="functionBody">
          
          <div>using the context of this minekey, rewrite the blob of HTML (argument) 
looking for strings of the form:</p>
<p>HREF=/api/data/99 HREF=/api/data/99/dummy.html 
HREF='/api/data/99/dummy.html' HREF=&quot;/api/data/99&quot; 
SRC=/api/icon/99/dummy.png SRC='/api/icon/99' 
SRC=&quot;/api/icon/99/dummy.png&quot;</p>
<p>...where 99 is an example iid; the rewriter replacing the 99 with the 
results of self.spawn_data(iid).permalink() - in other words a URL 
customised to retreive that item/iid with decremented depth.</p>
<p>The rewriter tries to be semi-clever, but not very, alas; it does not 
check that we are currently inside a &lt;TAG&gt; before rewriting such 
strings.  When BeautifulSoup comes in, that will change.</p>
<p>if the /api/icon/99/dummy.png URL is prefixed with either a single or 
double-quote, the rewriter checks that the substring to be rewritten ends 
with a corresponding quote; this is inadequate but should hope with 
unbalanced quotation marks during development.</p>
<p>if the URL does NOT begin with a quote character, the rewriter ignores 
what the last character of the matched string, irrespective of whether it 
is a quote character or not.</p>
<p>if any sanity-check fails, the rewriter simply does not rewrite the 
HTML.<table class="fieldTable"></table></div>
        </div>
      </div>
    
    <address>
      <a href="index.html">API Documentation</a> for pymine, generated by <a href="http://codespeak.net/~mwh/pydoctor/">pydoctor</a> at 2010-04-07 23:15:24.
    </address>
  </body>
</html>